Safe, Fast, and user-friendly wrapper around the CUDA Driver API.
# Low level CUDA interop
Because additions to CUDA and libraries that use CUDA are everchanging, this library
provides unsafe functions for retrieving and setting handles to raw cuda_sys objects.
This allows advanced users to embed libraries that rely on CUDA, such as OptiX. We
also re-export cuda_sys as a [`sys`] module for convenience.
# CUDA Terminology:
## Devices and Hosts:
This crate and its documentation uses the terms "device" and "host" frequently, so it's worth
explaining them in more detail. A device refers to a CUDA-capable GPU or similar device and its
associated external memory space. The host is the CPU and its associated memory space. Data
must be transferred from host memory to device memory before the device can use it for
computations, and the results must then be transferred back to host memory.
## Contexts, Modules, Streams and Functions:
A CUDA context is akin to a process on the host - it contains all of the state for working with
a device, all memory allocations, etc. Each context is associated with a single device.
A Module is similar to a shared-object library - it is a piece of compiled code which exports
functions and global values. Functions can be loaded from modules and launched on a device as
one might load a function from a shared-object file and call it. Functions are also known as
kernels and the two terms will be used interchangeably.
A Stream is akin to a thread - asynchronous work such as kernel execution can be queued into a
stream. Work within a single stream will execute sequentially in the order that it was
submitted, and may interleave with work from other streams.
## Grids, Blocks and Threads:
CUDA devices typically execute kernel functions on many threads in parallel. These threads can
be grouped into thread blocks, which share an area of fast hardware memory known as shared
memory. Thread blocks can be one-, two-, or three-dimensional, which is helpful when working
with multi-dimensional data such as images. Thread blocks are then grouped into grids, which
can also be one-, two-, or three-dimensional.
CUDA devices often contain multiple separate processors. Each processor is capable of excuting
many threads simultaneously, but they must be from the same thread block. Thus, it is important
to ensure that the grid size is large enough to provide work for all processors. On the other
hand, if the thread blocks are too small each processor will be under-utilized and the
code will be unable to make effective use of shared memory.
# Usage:
Before using cust, you must install the CUDA development libraries for your system. Version
9.0 or newer is required. You must also have a CUDA-capable GPU installed with the appropriate
drivers.
Cust will try to find the CUDA libraries automatically, if it is unable to find it, you can set
`CUDA_LIBRARY_PATH` to some path manually.